home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat3 / Tcl / crttrace.z / crttrace
Text File  |  1998-10-30  |  9KB  |  199 lines
  1.  
  2.  
  3.  
  4. TTTTccccllll____CCCCrrrreeeeaaaatttteeeeTTTTrrrraaaacccceeee((((3333TTTTccccllll))))                                    TTTTccccllll____CCCCrrrreeeeaaaatttteeeeTTTTrrrraaaacccceeee((((3333TTTTccccllll))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      Tcl_CreateTrace, Tcl_DeleteTrace - arrange for command execution to be
  10.      traced
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ttttccccllll....hhhh>>>>
  14.  
  15.      Tcl_Trace
  16.      TTTTccccllll____CCCCrrrreeeeaaaatttteeeeTTTTrrrraaaacccceeee(_i_n_t_e_r_p, _l_e_v_e_l, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  17.  
  18.      TTTTccccllll____DDDDeeeelllleeeetttteeeeTTTTrrrraaaacccceeee(_i_n_t_e_r_p, _t_r_a_c_e)
  19.  
  20. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  21.      Tcl_Interp         *_i_n_t_e_r_p          (in)      Interpreter containing
  22.                                                    command to be traced or
  23.                                                    untraced.
  24.  
  25.      int                _l_e_v_e_l            (in)      Only commands at or below
  26.                                                    this nesting level will be
  27.                                                    traced.  1 means top-level
  28.                                                    commands only, 2 means
  29.                                                    top-level commands or those
  30.                                                    that are invoked as
  31.                                                    immediate consequences of
  32.                                                    executing top-level
  33.                                                    commands (procedure bodies,
  34.                                                    bracketed commands, etc.)
  35.                                                    and so on.
  36.  
  37.      Tcl_CmdTraceProc   *_p_r_o_c            (in)      Procedure to call for each
  38.                                                    command that's executed.
  39.                                                    See below for details on
  40.                                                    the calling sequence.
  41.  
  42.      ClientData         _c_l_i_e_n_t_D_a_t_a       (in)      Arbitrary one-word value to
  43.                                                    pass to _p_r_o_c.
  44.  
  45.      Tcl_Trace          _t_r_a_c_e            (in)      Token for trace to be
  46.                                                    removed (return value from
  47.                                                    previous call to
  48.                                                    TTTTccccllll____CCCCrrrreeeeaaaatttteeeeTTTTrrrraaaacccceeee).
  49.  
  50.  
  51. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  52.      TTTTccccllll____CCCCrrrreeeeaaaatttteeeeTTTTrrrraaaacccceeee arranges for command tracing.  From now on, _p_r_o_c will be
  53.      invoked before Tcl calls command procedures to process commands in
  54.      _i_n_t_e_r_p.  The return value from TTTTccccllll____CCCCrrrreeeeaaaatttteeeeTTTTrrrraaaacccceeee is a token for the trace,
  55.      which may be passed to TTTTccccllll____DDDDeeeelllleeeetttteeeeTTTTrrrraaaacccceeee to remove the trace.  There may be
  56.      many traces in effect simultaneously for the same command interpreter.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. TTTTccccllll____CCCCrrrreeeeaaaatttteeeeTTTTrrrraaaacccceeee((((3333TTTTccccllll))))                                    TTTTccccllll____CCCCrrrreeeeaaaatttteeeeTTTTrrrraaaacccceeee((((3333TTTTccccllll))))
  71.  
  72.  
  73.  
  74.      _P_r_o_c should have arguments and result that match the type
  75.      TTTTccccllll____CCCCmmmmddddTTTTrrrraaaacccceeeePPPPrrrroooocccc:
  76.  
  77.           typedef void Tcl_CmdTraceProc(
  78.                ClientData _c_l_i_e_n_t_D_a_t_a,
  79.                Tcl_Interp *_i_n_t_e_r_p,
  80.                int _l_e_v_e_l,
  81.                char *_c_o_m_m_a_n_d,
  82.                Tcl_CmdProc *_c_m_d_P_r_o_c,
  83.                ClientData _c_m_d_C_l_i_e_n_t_D_a_t_a,
  84.                int _a_r_g_c,
  85.                char *_a_r_g_v[]));
  86.  
  87.      The _c_l_i_e_n_t_D_a_t_a and _i_n_t_e_r_p parameters are copies of the corresponding
  88.      arguments given to TTTTccccllll____CCCCrrrreeeeaaaatttteeeeTTTTrrrraaaacccceeee.  _C_l_i_e_n_t_D_a_t_a typically points to an
  89.      application-specific data structure that describes what to do when _p_r_o_c
  90.      is invoked.  _L_e_v_e_l gives the nesting level of the command (1 for top-
  91.      level commands passed to TTTTccccllll____EEEEvvvvaaaallll by the application, 2 for the next-
  92.      level commands passed to TTTTccccllll____EEEEvvvvaaaallll as part of parsing or interpreting
  93.      level-1 commands, and so on).  _C_o_m_m_a_n_d points to a string containing the
  94.      text of the command, before any argument substitution.  _C_m_d_P_r_o_c contains
  95.      the address of the command procedure that will be called to process the
  96.      command (i.e. the _p_r_o_c argument of some previous call to
  97.      TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd) and _c_m_d_C_l_i_e_n_t_D_a_t_a contains the associated client data
  98.      for _c_m_d_P_r_o_c (the _c_l_i_e_n_t_D_a_t_a value passed to TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd).  _A_r_g_c and
  99.      _a_r_g_v give the final argument information that will be passed to _c_m_d_P_r_o_c,
  100.      after command, variable, and backslash substitution.  _P_r_o_c must not
  101.      modify the _c_o_m_m_a_n_d or _a_r_g_v strings.
  102.  
  103.      Tracing will only occur for commands at nesting level less than or equal
  104.      to the _l_e_v_e_l parameter (i.e. the _l_e_v_e_l parameter to _p_r_o_c will always be
  105.      less than or equal to the _l_e_v_e_l parameter to TTTTccccllll____CCCCrrrreeeeaaaatttteeeeTTTTrrrraaaacccceeee).
  106.  
  107.      Calls to _p_r_o_c will be made by the Tcl parser immediately before it calls
  108.      the command procedure for the command (_c_m_d_P_r_o_c).  This occurs after
  109.      argument parsing and substitution, so tracing for substituted commands
  110.      occurs before tracing of the commands containing the substitutions.  If
  111.      there is a syntax error in a command, or if there is no command procedure
  112.      associated with a command name, then no tracing will occur for that
  113.      command.  If a string passed to Tcl_Eval contains multiple commands
  114.      (bracketed, or on different lines) then multiple calls to _p_r_o_c will
  115.      occur, one for each command.  The _c_o_m_m_a_n_d string for each of these trace
  116.      calls will reflect only a single command, not the entire string passed to
  117.      Tcl_Eval.
  118.  
  119.      TTTTccccllll____DDDDeeeelllleeeetttteeeeTTTTrrrraaaacccceeee removes a trace, so that no future calls will be made to
  120.      the procedure associated with the trace.  After TTTTccccllll____DDDDeeeelllleeeetttteeeeTTTTrrrraaaacccceeee returns,
  121.      the caller should never again use the _t_r_a_c_e token.
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. TTTTccccllll____CCCCrrrreeeeaaaatttteeeeTTTTrrrraaaacccceeee((((3333TTTTccccllll))))                                    TTTTccccllll____CCCCrrrreeeeaaaatttteeeeTTTTrrrraaaacccceeee((((3333TTTTccccllll))))
  137.  
  138.  
  139.  
  140. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  141.      command, create, delete, interpreter, trace
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.